home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / gemfst15.lzh / GEMFBIND.DOC < prev    next >
Text File  |  1990-06-29  |  16KB  |  313 lines
  1.  
  2. ***************************************************************************
  3.                                 GEMFAST
  4.                        Public Domain GEM bindings
  5.                               by Ian Lepore
  6. ***************************************************************************
  7.  
  8. This document provides general background on the GEMFAST bindings system,
  9. installation and usage information, and documents some of the internals 
  10. applicable to the C programmer.
  11.  
  12. ---------------------------------------------------------------------------
  13.                             DOCUMENT CONTENTS
  14. ---------------------------------------------------------------------------
  15.  
  16.  1.0  -  Packing List
  17.  2.0  -  Background
  18.  3.0  -  Functions supported by the bindings
  19.  4.0  -  Installation and Usage
  20.  5.0  -  About the GEMFAST.H header file
  21.  6.0  -  Notes
  22.  7.0  -  Bugs
  23.  8.0  -  Support
  24.  9.0  -  About the (non-existant) copyright
  25.  
  26. ---------------------------------------------------------------------------
  27.  1.0                          PACKING LIST 
  28.                  (xx = version, eg '10' = version 1.0)
  29. ---------------------------------------------------------------------------
  30.  
  31.      GEMFSTxx.ARC     - The runtime system, includes the following...
  32.         AESFAST.A     - The AES bindings library.
  33.         VDIFAST.A     - The VDI bindings library.
  34.         GEMFAST.H     - The C-language header file for use with GEMFAST.
  35.         GEMF_Vxx.DOC  - Version-specific release notes and revision history.
  36.         GEMUTIL.DOC   - Documentation on non-standard utility functions.
  37.         GEMXTEND.DOC  - Documentation on GEM extensions (Atari's and mine).
  38.         GEMFBIND.DOC  - Installation and usage documentation.
  39.  
  40.      GEMFSCxx.ARC    - Source code for the package.  
  41.         AESSRCxx.ARC - Source code for the AES bindings and utilities.
  42.         VDISRCxx.ARC - Source code for the VDI bindings.
  43.  
  44.      GEMFXMxx.ARC    - Example programs.
  45.         MINICOLR.ARC - Example desk accessory, a mini color pallete control.
  46.         MEMFIND.ARC  - Example dialog-based program, displays free memory.
  47.         WINDXMPL.ARC - Example of object tree display in a window.
  48.         
  49.      GEMFUTxx.ARC    - The GEMFAST utilities in C source code format.
  50.      
  51. ---------------------------------------------------------------------------
  52. 2.0                            BACKGROUND
  53. ---------------------------------------------------------------------------
  54.  
  55. These binding libraries were written to address two needs: 1) The world 
  56. needed a good set of free GEM bindings to complement the various PD C
  57. compilers that are available, and 2) The bindings available with most 
  58. commercial compilers aren't so hot either.
  59.  
  60. These routines have been written to be faster than your typical GEM 
  61. bindings.  As a secondary consideration, I tried to make them smaller as 
  62. well.  When you recompile an application using these libararies, you 
  63. should notice a drop in program size, and the link phase of the compile 
  64. should run faster (your mileage may vary).  The design goals included 
  65. using as little bss and data memory as possible (the stack is used for
  66. temporary storage as needed), and that references requiring relocation 
  67. fixup be kept to a minimum.
  68.  
  69. These bindings are known to be compatible with Alcyon C, Sozobon C, and 
  70. Laser C.  They should be compatible with any compiler/linker system 
  71. which uses 'DRI-standard' object & library file formats.  In addition,
  72. the C source code version of the utilities should work with any C compiler.
  73. There will be support for MWC *someday*, but I will NOT commit to a date.
  74.  
  75. ---------------------------------------------------------------------------
  76. 3.0               FUNCTIONS SUPPORTED IN THESE BINDINGS
  77. ---------------------------------------------------------------------------
  78.  
  79. The VDIFAST library includes most of the functions documented in the 
  80. Digital Research publication _GEM Programmer's Guide Vol 1: VDI_.  Some 
  81. of the VDI functions are missing from the VDIFAST library, 
  82. notably the 'Polaroid Pallete' stuff, the v_cellarray() functions, and 
  83. similar rarely-used items.
  84.  
  85. The AESFAST library includes all AES functions documented in the DRI 
  86. publication _GEM Programmer's Guide Vol 2: AES_.  Also included are the 
  87. 'standard' AES utility functions (rc_intersect, etc), and a collection 
  88. of non-standard utilities of my own.  The document file GEMUTIL.DOC 
  89. describes the utility functions.  The AES functions that Atari added 
  90. beginning with TOS 1.4 are also supported.  See GEMXTEND.DOC for more
  91. information.  (As of GemFast release 1.4, a new calling standard for AES
  92. functions has been added.  These are documented in GEMXTEND.DOC).
  93.  
  94. The DRI documents cited above are the definitive reference for the 
  95. standard AES & VDI functions.  If you are using other documents (such as 
  96. Abacus books) there may be some variations between your documents and 
  97. the libraries.  Sorry, I decided it was safer to use the original DRI 
  98. docs as my source of info.  TOS 1.4 functions were built to the
  99. specs in the TOS 1.4 developer's release notes, and thus ARE SUBJECT TO
  100. CHANGE, depending on what Atari does with the final release of TOS 1.4.
  101.  
  102. ---------------------------------------------------------------------------
  103. 4.0                       INSTALLATION AND USAGE
  104. ---------------------------------------------------------------------------
  105.  
  106. Copy the VDIFAST.A and AESFAST.A files to the drive and path where your 
  107. linker will look for runtime-library files.  (EG:  \sozobon\lib). Copy 
  108. the GEMFAST.H file to the drive and path where your compiler looks for 
  109. include files (EG: \sozobon\include).
  110.  
  111. If you are using the Atari 'aln' linker, you will need to use aln's 
  112. DOINDEX program to create .NDX files for each of the libraries.  ALWAYS
  113. BE SURE TO RE-INDEX THE LIBRARY WHEN YOU INSTALL A NEW VERSION OF THE
  114. BINDINGS!
  115.  
  116. To link with the GEMFAST libraries, just enter the library names on the 
  117. command line for the linker program.  For example (using Sozobon):
  118.  
  119.   ld -o myprog.prg dstart.o myprog.o dlibs.a vdifast.a aesfast.a
  120.                          or
  121.   cc -o myprog.prg myprog.c vdifast.a aesfast.a
  122.  
  123. It should not matter where on the command line the names of the GEMFAST 
  124. libs appear:  each library is self-contained, and the linker will not 
  125. have to resolve references between libraries.  No special code is needed 
  126. in your startup object file; you may continue to use whatever startup file
  127. (dstart.o, apstart.o, etc) you currently use.  Also, unlike some GEM 
  128. bindings, you do NOT need to include the VDI bindings libarary if your 
  129. program uses only AES function calls.
  130.  
  131. (An aside:  I've seen a lot of programs that open a VDI workstation, and 
  132. then use only AES functions within the program.  If you use only AES 
  133. functions, you do NOT need to open a VDI virtual workstation.)
  134.  
  135. ---------------------------------------------------------------------------
  136. 5.0                   ABOUT THE GEMFAST HEADER FILE
  137. ---------------------------------------------------------------------------
  138.  
  139. All VDI and AES functions return an 'int' or are of type 'void' 
  140. (returning nothing).  Given the lack of ST C compilers which support 
  141. function prototyping, a header file full of 'extern int xxx()' type 
  142. declarations is a waste of compile time.  The GEMFAST.H file contains 
  143. constants and structures commonly used in GEM programming.
  144.  
  145. If your current bindings system uses OBDEFS.H and GEMDEFS.H, remove the
  146. #include statements for those files, and insert #include <gemfast.h> in
  147. your source code.  While it is possible to continue using your old header
  148. files, your code will become less compatible as future versions of GEMFAST
  149. are released, as the GEMFAST.H file now contains #defines to redirect some
  150. old utility function names to the new names.  Also, the GEMFAST.H file
  151. contains #define GEMFAST_H 1, and code is gonna hit the PD pretty soon that
  152. requires that constant to be set to correctly detect that the GEMFAST
  153. bindings are being used.
  154.  
  155. If you have a lot of existing code that #include's OBDEFS and GEMDEFS, you
  156. can painlessly upgra